Using the Scroll View nodes

Use the Scroll View nodes to define an area where to generate scrolling messages in response to user input and physics-based animation. For example, you can use the scroll message with its parameters generated by a Scroll View node to move a map plane or rotate a mesh.

The Scroll View defines an interactive area and sends the messages reflecting the changes in the scroll position. The position and size of a Scroll View node define where the Scroll View registers input. After you create a Scroll View node you have to define what happens in response to scroll position changes. For example, you can use a Scroll View node to move 3D objects. See Tutorial: Rotate a 3D model.

The Scroll View reports changes of its scroll position through the Scrolled trigger. You can add actions to react to these messages to, for example, set the position of an object according to the scrolling.

Scroll View 3D is a 3D control, so take into account that the orientation towards the viewer is important. A Scroll View node tracks user input along the focus plane that is in the center of the Scroll View node. Make sure that you do not rotate this focus plane so that it is either perpendicular to or faces away from the viewer.

When a Scroll View node has focus, you can scroll the contents of that node using the Left Arrow, Right Arrow, Up Arrow, and Down Arrow keyboard keys.

Creating a scroll view

To create a scroll view:

1. In the Project press Alt and right-click the node where you want to create a Scroll View node and select either Scroll View 3D, or Scroll View 2D.
   Note that you can create a 3D node only inside 3D nodes, and 2D node only inside 2D nodes.
2. In the Project create a node that works as an input plane you want to control with scroll gestures.
   For example, if you created a Scroll View 3D node, add a Plane, if you created a Scroll View 2D, add an Image.
3. In the Project select the Scroll View, in the Node Components > Triggers section click + Add Triggers, and in the Add Triggers window add one of the triggers from the Scroll View category.
   For example, add the Scrolled trigger.
   
4. In the Node Components in the Scrolled trigger click the Add dropdown menu and select one of the actions.
   For example, select the Set Property action and set:
   • Target Item to the object you want to control with the Scroll View node.
     If you created a Scroll View 3D and a Plane, select that Plane. If you created a Scroll View 2D and an Image, select that Image.
   • Target Property to the property you want to affect with the Scroll View node.
     If you created a Scroll View 3D, select Render Transformation. If you created a Scroll View 2D, select Render Transformation.
   • Target Property Attribute to the attribute you want to control with the Scroll View node.
     To scroll the object along the x axis, select Translation X.
   • Value From to Message
   • Message to the same axis in the Target Property Attribute
     For example, if you selected Translation X, select Position X.

   Click Save.
   
   In the Preview when you click and drag along the x axis within the Scroll View node, the object you set as the Target Item of the Set Property action of the Scrolled trigger moves according to the settings defined by the Scroll View node.

5. (Optional) In the Project select the Scroll View and in the Properties adjust the threshold, acceleration, drag, and other settings to create a scroll view that responds to user input the way you want it to respond:
   • Scroll Sensitivity property sets how much the position changes relative to the movement of the pointer that starts the swiping. The higher the value the more the position of the object controlled by the Scroll View node changes. Negative values move the object in the opposite direction.
   • Sliding Accerelation property sets the acceleration of the object after you release the pointer with which you swipe. Use low values when you want the object controlled by the Scroll View node to slowly reach the final position. Use high values when you want the object to quickly reach the final position .
   • Sliding Drag property sets how much drag affects the movement of the object after you release the pointer with which you swipe. The lower the value the higher the drag and the faster the sliding of the object controlled by the Scroll View node stops.
   • Scroll Bounds Minimum and Scroll Bounds Maximum properties set the minimum and maximum values for the scroll bounds. Scroll bounds define where the scrolling begins and ends.
   • Looping X Enabled and Looping Y Enabled properties set the object to start scrolling from the beginning when the scroll reaches the scroll bounds on the x or y axis. Use the Scroll Bounds Minimum and Scroll Bounds Maximum properties to set the scroll bounds.
   

Debugging a scroll view

To test whether the scroll view is working properly, add to the scroll view trigger you are using a Write Log action. Every time you use the scroll view, Kanzi Studio writes a message to the Log window.

Setting the background of a Scroll View 2D

Use brushes to set the background of 2D nodes. In Kanzi all 2D nodes by default have transparent background.

To set the background:

1. Create a Color Brush, a Texture Brush, or a Material Brush. See Using brushes.
   
2. In the Project select the 2D node the background of which you want to paint.
   Note that you can set only the background of 2D nodes.
3. In the Properties add the Background Brush property and select the brush you created in the first step.
   

Scroll view example

This example shows how to use the Scroll View node as a controller for moving a map plane in a scene. In the example the Kanzi Studio project contains a Scroll View node which translates the scroll position coordinates to the translation fields of a node. The example implements more advanced features in the C++ application using the Kanzi Engine API.

A key aspect in using the Scroll View node is the controlling of input sensitivity based on the distance of the scroll view plane from the camera. This example uses a one-to-one mapping with the background plane by positioning them at the same distance and orientation from the camera. Scroll view and the background plane, however, are not tied together under the same translation because that way the input coordinate space would move along with the background plane during the user's panning gesture. By positioning the scroll view plane further from the camera, the sensitivity of scroll view gestures increases.

This example demonstrates the use of a raw InterpolatedValue instance in the C++ application for afflicting a z-offset (zoom) based on the velocity of the movement.

The scroll view as well as the trajectory list box components manipulate input to output coordinates through a value interpolator, effectively allowing for smoother gesture mappings that are often most suitable for touchscreen based interactions.

You can find the example in the <KanziWorkspace>/Examples/Scroll_view directory.

Using the Scroll View 3D node in the API

To create a Scroll View 3D node that animates the transformation of a 3D node in response to scroll messages:

Node3DSharedPtr m_box;

// Handler for ScrollView3D.Scrolled message from scroll view.
void onScrollViewScrolled(ScrollView3D::ScrollMessageArguments& messageArguments)
{
    Vector3 translation = Vector3(messageArguments.getScrollPositionX(), messageArguments.getScrollPositionY(), 0);
    SRTValue3D transformation = SRTValue3D::createTranslation(translation);

    m_box->setRenderTransformation(transformation);
}

void exampleScrollView3D()
{
    ScreenSharedPtr testScreen;
    Node2DSharedPtr testRootLayer;
    ScrollView3DSharedPtr scrollView;
    createTree(testScreen, testRootLayer, scrollView);

    scrollView->setSize(100, 100, 10);

    m_box = Model3D::createBox(domain, "Box", Vector3(2.0f, 2.0f, 2.0f), ThemeOrange);
    scrollView->addChild(m_box);

    // Add message handler for ScrollView3D.Scrolled message from scroll view.
    scrollView->addMessageHandler(ScrollView3D::ScrolledMessage, bind(&ScrollView3DSnippet::onScrollViewScrolled, this, placeholders::_1));

    m_box.reset();
}

To create a Scroll View 3D node that animates the transformation of a 3D node in response to zoom messages:

Node3DSharedPtr m_box;
SRTValue3D m_transformUnscaled;

// Handler for ScrollView3D.Zoomed message from scroll view.
void onScrollViewZoomed(ScrollView3D::ZoomedMessageArguments& arguments)
{
    float zoom = arguments.getZoom();
    m_transformUnscaled.scale(Vector3(zoom, zoom, zoom));
    m_box->setRenderTransformation(m_transformUnscaled);
}

void createScene()
{
    ScreenSharedPtr screen;
    Node2DSharedPtr rootLayer;
    ScrollView3DSharedPtr scrollView;
    createTree(screen, rootLayer, scrollView);

    scrollView->setSize(100, 100, 10);

    m_box = Model3D::createBox(domain, "Box", Vector3(2.0f, 2.0f, 2.0f), ThemeOrange);
    scrollView->addChild(m_box);
    m_transformUnscaled = m_box->getRenderTransformation();

    // Add message handler for ScrollView3D.Zoomed message from scroll view.
    scrollView->addMessageHandler(ScrollView3D::ZoomedMessage, bind(&ScrollViewZoomSnippet::onScrollViewZoomed, this, placeholders::_1));

    m_box.reset();
}

Using the Scroll View 2D node in the API

To create a Scroll View 2D node that animates the transformation of a 2D node in response to scroll messages:

Node2DSharedPtr textNode;

// Handler for ScrollView2D.Scrolled message from scroll view.
void onScrollViewScrolled(ScrollView2D::ScrollMessageArguments& messageArguments)
{
    Vector2 translation = Vector2(messageArguments.getScrollPositionX(), messageArguments.getScrollPositionY());
    textNode->setRenderTransformation(SRTValue2D::createTranslation(translation));
}

void exampleScrollView2D()
{
    ScreenSharedPtr testScreen;
    Node2DSharedPtr rootNode;
    ScrollView2DSharedPtr scrollView;
    createTree(testScreen, rootNode, scrollView);

    scrollView->setWidth(100);
    scrollView->setHeight(100);

    textNode = TextBlock2D::create(domain, "Hello world!");
    scrollView->addChild(textNode);

    // Add message handler for ScrollView2D.Scrolled message from scroll view.
    scrollView->addMessageHandler(ScrollView2D::ScrolledMessage, bind(&ScrollView2DSnippet::onScrollViewScrolled, this, placeholders::_1));

    textNode.reset();
}

See also

Triggers

Using brushes

Tutorial: Rotate a 3D model

Open topic with navigation